Using kzb binaries

Kzb binaries contain contents of your Kanzi Studio projects. To run your Kanzi application on a device, you need to export it as a .kzb binary.

Creating a kzb binary from a Kanzi Studio project

To create a kzb binary from a Kanzi Studio project, open your Kanzi Studio project in Kanzi Studio and select File > Export KZB Binary.

Kanzi Studio creates these files:

<ProjectName>.kzb contains the content of your project in binary format.
<ProjectName>.kzb.txt contains a list of paths to project items in the kzb binary. You can use these paths to access the content of your Kanzi application in the application code.
<ProjectName>.kzb.cfg contains a list of kzb binary files. If your Kanzi application includes application code, Kanzi by default configures the C application to load the binaries listed in this file
```
configuration->binaryName = "<ProjectName>.kzb.cfg"
```

If you export kzb binary of a Kanzi Studio project without C application, Kanzi Studio creates these files in <KanziWorkspace>/Projects/<ProjectName>/Binary, otherwise it creates these files in <KanziWorkspace>/Projects/<ProjectName>/Application/bin.

Using multiple kzb binaries created from a project with profiles

You can load the content of your Kanzi application from multiple kzb binaries. For example, you can have different profiles in your Kanzi Studio project to match different screen sizes of your target devices. You can then add a C application to your Kanzi project to load only the binary that matches the screen size of user's device. See Profiles.

To use multiple kzb binaries created with profiles:

Create a Kanzi Studio project with profiles. See Using profiles.
For example, set different values for the Screen Resolution property to match different screen sizes of your target devices.
Select File > Export Profile Binaries.
Kanzi Studio exports a master binary and one binary for each profile in your project.
In the C application code of your Kanzi application, use the configuration file of the binary of the profile you want to load.
```
configuration->binaryName = "Hello_World_800x480.kzb.cfg"
```

Creating an application from kzb binaries from several Kanzi Studio projects

You can create a Kanzi application that loads its content from multiple kzb binaries. This way you can combine multiple Kanzi Studio projects into one Kanzi application when a user starts your Kanzi application.

When you want to use the same scene graph for your Kanzi application, use the same project name for all the projects you want to combine into one Kanzi application. When combining projects with the same name, each project item in the same location of the scene graph and the same name as a project item in another kzb file is overwritten by the item from the kzb file that is listed last in the kzb.cfg file. For example, if you have two kzb files named ProjectOne and each contains an object named Screen in the same location in the scene graph, Kanzi uses the Screen object contained by the project listed last in the kzb.cfg. You can achieve a similar result by merging several Kanzi Studio projects in Kanzi Studio. See Merging projects.

When you want to use different scene graphs for your Kanzi application, use different project names for each project you want to combine into a single Kanzi application. You can combine projects with different names only in code.

To create and application from kzb binaries from several Kanzi Studio projects with different names:

Create a master project and export it as a kzb binary. See Creating a kzb binary from a Kanzi Studio project.
Because you combine multiple kzb binaries in native code, create your master project with a C application.
For example, create a project that contains just the loading screen of your Kanzi application.
Create the rest of your Kanzi application in one or more Kanzi Studio projects and do this:
- Add the scene render pass as a resource:
  1. In Context Resources in the scope of the viewport layer that contains the scene you use in your Kanzi application click Add resource, and add the render pass you use for rendering that scene.
  2. In the Project select the scene you want to use in your Kanzi application, and in the Properties set the Composer property to the render pass you added to the scope of the viewport layer.
- In Library select the render pass you use to render the scene, and in the properties Color Buffer enable the Clear Enabled property only for the binary you load first. For all the binaries you load after the first binary disable the Clear Enabled property.
When you are ready to use the content from these projects with your master project, in the Project select the project root and in the Properties make sure the Master Project property is disabled.
The project root item contains settings for binary export in the category Binary Export Details. You can use these properties to optimize the performance of your application.
For each kzb binary you want to use in your Kanzi application, export the kzb binary by selecting File > Export KZB Binary.
Kanzi Studio creates the kzb binary with configuration files. If you export kzb binary of a Kanzi Studio project without C application, Kanzi Studio creates these files in <KanziWorkspace>/Projects/<ProjectName>/Binary, otherwise it creates these files in <KanziWorkspace>/Projects/<ProjectName>/Application/bin.
Place the kzb binaries you exported in the previous step to the <KanziWorkspace>/Projects/<ProjectName>/Application/bin directory of your master project.
Add the kzb binaries to the kzb.cfg file of your master project.
For example, if your master project is called Loading screen, and you are loading projects with names Additional binary one and Additional binary two, the kzb.cfg file of your master project looks like this
```
Loading_screen.kzb
Additional_binary_one.kzb
Additional_binary_two.kzb
```

In the C application code of your master project, create a function that loads the additional binaries.
For example, if your master kzb binary contains only a loading screen and you want to load two kzb binaries that contains the content, in the C application of the master project:

Include the required headers.
The headers you need to include depend on the content of the kzb binaries you want to include in your Kanzi application. For example, if you want to acquire or change other resources, such as materials, then you have to include the header that handles materials (kzu_material.h).

// Kanzi uses the resource manager to acquire resources from kzb,
// and to add the kzb binaries to the resource manager.
#include <user/resource/kzu_resource_manager.h>
// UI domain is a common container for the most of Kanzi structures,
// such as, common resource manager, task scheduler, and so on.
#include <user/ui/kzu_ui_domain.h>
// Memory manager is required for holding the memory allocations,
// and many constructor functions require it.
#include <core/memory/kzc_memory_manager.h>
// Kanzi uses kzu_prefab.h to instantiate prefab templates
#include <user/ui/templates/kzu_prefab.h>
// Kanzi uses kzu_object.h to modify the object scene graph
#include <user/scene_graph/kzu_object.h>
// Kanzi uses kzu_layer.h to access the root layer in this example.
#include <user/layers/kzu_layer.h>

Create a function that loads the additional kzb binaries.

KZ_CALLBACK kzsError loadAdditionalBinaries(struct KzaApplication* application)
{
	// Gets the resources from the kzb binaries and instantiates them as a prefab template.
	struct KzuResource* prefabResource;
	struct KzuLayer* rootLayer;
	rootLayer = kzaApplicationGetRootLayer(application);

	// First binary
	// Acquires a resource from the resource manager based on the provided URL.
	kzuResourceManagerAcquireResource(kzuUIDomainGetResourceManager(
		kzaApplicationGetUIDomain(application)),
		"kzb://Additional_binary_one/Prefabs/Viewport Layer", &prefabResource);
	{
		struct KzuObjectNode* prefabInstanceNode;
		// Instantiates a prefab template.
		kzuPrefabTemplateInstantiate(kzuPrefabTemplateFromResource(prefabResource),
			"RootOne", &prefabInstanceNode);
		// Adds the instanced viewport layer as a child of the root layer.
		kzuObjectNodeAddChild(kzuLayerToObjectNode(rootLayer), prefabInstanceNode);
	}

	// Second binary
	// Acquires a resource from the resource manager based on the provided URL.
	kzuResourceManagerAcquireResource(kzuUIDomainGetResourceManager(
		kzaApplicationGetUIDomain(application)),
		"kzb://Additional_binary_two/Prefabs/Viewport Layer", &prefabResource);
	{
		struct KzuObjectNode* prefabInstanceNode;
		// Instantiates a prefab template.
		kzuPrefabTemplateInstantiate(kzuPrefabTemplateFromResource(prefabResource),
		"RootTwo", &prefabInstanceNode);
		// Adds the instanced viewport layer as a child of the root layer.
		kzuObjectNodeAddChild(kzuLayerToObjectNode(rootLayer), prefabInstanceNode);
	}

	kzsSuccess();
}

In the kzApplicationConfigure after loading the master kzb binary, call the function that loads the additional kzb binaries.

KZ_CALLBACK void kzApplicationConfigure(const struct KzaSystemProperties* systemProperties,
	struct KzaApplicationProperties* configuration)
{
	configuration->memoryPoolSize = 20 * 1024 * 1024;
	// Loads the master kzb binary.
	configuration->binaryName = "Loading_screen.kzb.cfg";
	// Loads the additional kzb binaries when the master project loads.
	configuration->onProjectLoaded = loadAdditionalBinaries;

	configuration->onKeyInputEvent = keyInputEventHandler;
}

Using kzb binaries

Creating a kzb binary from a Kanzi Studio project

Using multiple kzb binaries created from a project with profiles

Creating an application from kzb binaries from several Kanzi Studio projects

See also